WebCodecs VideoFrame Plane-tilgang: Et dypdykk i manipulering av rå videodata

I årevis føltes høytytende videobehandling i nettleseren som en fjern drøm. Utviklere var ofte begrenset til begrensningene i <video>-elementet og 2D Canvas API-et, som, selv om de er kraftige, introduserte ytelsesflaskehalser og begrenset tilgang til de underliggende rå videodataene. Ankomsten av WebCodecs API-et har fundamentalt endret dette landskapet, og gir lavnivåtilgang til nettleserens innebygde mediekodeker. En av de mest revolusjonerende funksjonene er muligheten til å få direkte tilgang til og manipulere rådataene til individuelle videorammer gjennom VideoFrame-objektet.

Denne artikkelen er en omfattende guide for utviklere som ønsker å gå utover enkel videoavspilling. Vi vil utforske detaljene ved VideoFrame-plan-tilgang, avmystifisere konsepter som fargerom og minne-layout, og gi praktiske eksempler for å gi deg muligheten til å bygge neste generasjon av videoapplikasjoner i nettleseren, fra sanntidsfiltre til sofistikerte datasynsoppgaver.

Forutsetninger

For å få mest mulig ut av denne guiden, bør du ha en solid forståelse av:

• Moderne JavaScript: Inkludert asynkron programmering (async/await, Promises).
• Grunnleggende videokonsepter: Kjennskap til begreper som rammer, oppløsning og kodeker er nyttig.
• Nettleser-API-er: Erfaring med API-er som Canvas 2D eller WebGL vil være en fordel, men er ikke strengt nødvendig.

Forståelse av videorammer, fargerom og plan

Før vi dykker ned i API-et, må vi først bygge en solid mental modell av hvordan dataene i en videoramme faktisk ser ut. En digital video er en sekvens av stillbilder, eller rammer. Hver ramme er et rutenett av piksler, og hver piksel har en farge. Hvordan den fargen lagres, defineres av fargerommet og pikselformatet.

RGBA: Nettets morsmål

De fleste nettutviklere er kjent med RGBA-fargemodellen. Hver piksel representeres av fire komponenter: Rød, Grønn, Blå og Alfa (gjennomsiktighet). Dataene lagres vanligvis interleaved (sammenflettet) i minnet, noe som betyr at R-, G-, B- og A-verdiene for en enkelt piksel lagres etter hverandre:

[R1, G1, B1, A1, R2, G2, B2, A2, ...]

I denne modellen lagres hele bildet i en enkelt, sammenhengende minneblokk. Vi kan tenke på dette som å ha et enkelt "plan" med data.

YUV: Språket for videokomprimering

Videokodeker jobber imidlertid sjelden direkte med RGBA. De foretrekker YUV (eller mer nøyaktig, Y'CbCr) fargerom. Denne modellen skiller bildeinformasjon i:

• Y (Luma): Lysstyrken eller gråskala-informasjonen. Det menneskelige øyet er mest følsomt for endringer i luma.
• U (Cb) og V (Cr): Krominans- eller fargedifferanseinformasjonen. Det menneskelige øyet er mindre følsomt for fargedetaljer enn for lysstyrkedetaljer.

Denne separasjonen er nøkkelen til effektiv komprimering. Ved å redusere oppløsningen til U- og V-komponentene – en teknikk kalt krominans-subsampling – kan vi redusere filstørrelsen betydelig med minimalt merkbart tap i kvalitet. Dette fører til planare pikselformater, der Y-, U- og V-komponentene lagres i separate minneblokker, eller "plan".

Et vanlig format er I420 (en type YUV 4:2:0), der for hver 2x2 blokk med piksler, er det fire Y-prøver, men bare én U- og én V-prøve. Dette betyr at U- og V-planene har halvparten av bredden og halvparten av høyden til Y-planet.

Å forstå denne forskjellen er kritisk fordi WebCodecs gir deg direkte tilgang til nettopp disse planene, nøyaktig slik dekoderen gir dem.

VideoFrame-objektet: Din inngangsport til pikseldata

Den sentrale brikken i dette puslespillet er VideoFrame-objektet. Det representerer en enkelt ramme med video og inneholder ikke bare pikseldataene, men også viktig metadata.

Nøkkelegenskaper for VideoFrame

• format: En streng som indikerer pikselformatet (f.eks. 'I420', 'NV12', 'RGBA').
• codedWidth / codedHeight: De fulle dimensjonene til rammen slik den er lagret i minnet, inkludert eventuell polstring som kreves av kodeken.
• displayWidth / displayHeight: Dimensjonene som skal brukes for å vise rammen.
• timestamp: Presentasjonstidsstempelet til rammen i mikrosekunder.
• duration: Varigheten til rammen i mikrosekunder.

Den magiske metoden: copyTo()

Hovedmetoden for å få tilgang til rå pikseldata er videoFrame.copyTo(destination, options). Denne asynkrone metoden kopierer rammens plandata til en buffer du oppgir.

• destination: Et ArrayBuffer eller en typet matrise (som Uint8Array) som er stor nok til å holde dataene.
• options: Et objekt som spesifiserer hvilke plan som skal kopieres og deres minne-layout. Hvis utelatt, kopieres alle plan til en enkelt sammenhengende buffer.

Metoden returnerer et Promise som resolver med en matrise av PlaneLayout-objekter, ett for hvert plan i rammen. Hvert PlaneLayout-objekt inneholder to avgjørende biter informasjon:

• offset: Byte-offseten der dette planens data begynner i destinasjonsbufferen.
• stride: Antall bytes mellom starten på en rad med piksler og starten på neste rad for det planet.

Et kritisk konsept: Stride vs. bredde

Dette er en av de vanligste kildene til forvirring for utviklere som er nye med lavnivå grafikkprogrammering. Du kan ikke anta at hver rad med pikseldata er tettpakket etter hverandre.

• Bredde er antall piksler i en rad av bildet.
• Stride (også kalt pitch eller linjesteg) er antall bytes i minnet fra starten av en rad til starten av den neste.

Ofte vil stride være større enn bredde * bytes_per_piksel. Dette er fordi minnet ofte polstres for å justeres med maskinvaregrenser (f.eks. 32- eller 64-byte grenser) for raskere behandling av CPU eller GPU. Du må alltid bruke stride for å beregne minneadressen til en piksel i en spesifikk rad.

Å ignorere stride vil føre til skjeve eller forvrengte bilder og feilaktig datatilgang.

Praktisk eksempel 1: Tilgang til og visning av et gråskalaplan

La oss starte med et enkelt, men kraftig eksempel. Mesteparten av video på nettet er kodet i et YUV-format som I420. 'Y'-planet er effektivt en komplett gråskala-representasjon av bildet. Vi kan trekke ut bare dette planet og rendre det til en canvas.

async function displayGrayscale(videoFrame) {
  // Vi antar at videoFrame er i et YUV-format som 'I420' eller 'NV12'.
  if (!videoFrame.format.startsWith('I4')) {
    console.error('Dette eksempelet krever et YUV 4:2:0 planart format.');
    videoFrame.close();
    return;
  }

  const yPlaneInfo = videoFrame.layout[0]; // Y-planet er alltid først.

  // Opprett en buffer for å holde kun Y-plan-dataene.
  const yPlaneData = new Uint8Array(yPlaneInfo.stride * videoFrame.codedHeight);

  // Kopier Y-planet inn i bufferen vår.
  await videoFrame.copyTo(yPlaneData, {
    rect: { x: 0, y: 0, width: videoFrame.codedWidth, height: videoFrame.codedHeight },
    layout: [yPlaneInfo]
  });

  // Nå inneholder yPlaneData de rå gråskalepikslene.
  // Vi må rendre det. Vi lager en RGBA-buffer for canvas.
  const canvas = document.getElementById('my-canvas');
  canvas.width = videoFrame.displayWidth;
  canvas.height = videoFrame.displayHeight;
  const ctx = canvas.getContext('2d');
  const imageData = ctx.createImageData(canvas.width, canvas.height);

  // Iterer over canvas-pikslene og fyll dem med data fra Y-planet.
  for (let y = 0; y < videoFrame.displayHeight; y++) {
    for (let x = 0; x < videoFrame.displayWidth; x++) {
      // Viktig: Bruk stride for å finne riktig kildeindeks!
      const yIndex = y * yPlaneInfo.stride + x;
      const luma = yPlaneData[yIndex];

      // Beregn destinasjonsindeksen i RGBA ImageData-bufferen.
      const rgbaIndex = (y * canvas.width + x) * 4;

      imageData.data[rgbaIndex] = luma;     // Rød
      imageData.data[rgbaIndex + 1] = luma; // Grønn
      imageData.data[rgbaIndex + 2] = luma; // Blå
      imageData.data[rgbaIndex + 3] = 255;  // Alfa
    }
  }

  ctx.putImageData(imageData, 0, 0);

  // KRITISK: Lukk alltid VideoFrame for å frigjøre minnet.
  videoFrame.close();
}

Dette eksempelet fremhever flere nøkkelsteg: identifisere riktig plan-layout, allokere en destinasjonsbuffer, bruke copyTo for å trekke ut dataene, og korrekt iterere over dataene ved hjelp av stride for å konstruere et nytt bilde.

Praktisk eksempel 2: In-place-manipulering (Sepiafilter)

La oss nå utføre en direkte datamanipulering. Et sepiafilter er en klassisk effekt som er enkel å implementere. For dette eksempelet er det enklere å jobbe med en RGBA-ramme, som du kan få fra en canvas eller en WebGL-kontekst.

async function applySepiaFilter(videoFrame) {
  // Dette eksempelet antar at input-rammen er 'RGBA' eller 'BGRA'.
  if (videoFrame.format !== 'RGBA' && videoFrame.format !== 'BGRA') {
    console.error('Sepiafilter-eksempelet krever en RGBA-ramme.');
    videoFrame.close();
    return null;
  }

  // Alloker en buffer for å holde pikseldataene.
  const frameDataSize = videoFrame.allocationSize();
  const frameData = new Uint8Array(frameDataSize);
  await videoFrame.copyTo(frameData);

  const layout = videoFrame.layout[0]; // RGBA er ett enkelt plan

  // Nå, manipuler dataene i bufferen.
  for (let y = 0; y < videoFrame.codedHeight; y++) {
    for (let x = 0; x < videoFrame.codedWidth; x++) {
      const pixelIndex = y * layout.stride + x * 4; // 4 bytes per piksel (R,G,B,A)

      const r = frameData[pixelIndex];
      const g = frameData[pixelIndex + 1];
      const b = frameData[pixelIndex + 2];

      const tr = 0.393 * r + 0.769 * g + 0.189 * b;
      const tg = 0.349 * r + 0.686 * g + 0.168 * b;
      const tb = 0.272 * r + 0.534 * g + 0.131 * b;

      frameData[pixelIndex] = Math.min(255, tr);
      frameData[pixelIndex + 1] = Math.min(255, tg);
      frameData[pixelIndex + 2] = Math.min(255, tb);
      // Alfa (frameData[pixelIndex + 3]) forblir uendret.
    }
  }

  // Opprett en *ny* VideoFrame med de modifiserte dataene.
  const newFrame = new VideoFrame(frameData, {
    format: videoFrame.format,
    codedWidth: videoFrame.codedWidth,
    codedHeight: videoFrame.codedHeight,
    timestamp: videoFrame.timestamp,
    duration: videoFrame.duration
  });

  // Ikke glem å lukke den opprinnelige rammen!
  videoFrame.close();

  return newFrame;
}

Dette demonstrerer en komplett lese-modifisere-skrive-syklus: kopier dataene ut, gå gjennom dem ved hjelp av stride, bruk en matematisk transformasjon på hver piksel, og konstruer en ny VideoFrame med de resulterende dataene. Denne nye rammen kan deretter rendres til en canvas, sendes til en VideoEncoder, eller gis videre til et annet behandlingstrinn.

Ytelse er viktig: JavaScript vs. WebAssembly (WASM)

Å iterere over millioner av piksler for hver ramme (en 1080p-ramme har over 2 millioner piksler, eller 8 millioner datapunkter i RGBA) i JavaScript kan være tregt. Selv om moderne JS-motorer er utrolig raske, kan denne tilnærmingen for sanntidsbehandling av høyoppløselig video (HD, 4K) lett overvelde hovedtråden, noe som fører til en hakkete brukeropplevelse.

Det er her WebAssembly (WASM) blir et essensielt verktøy. WASM lar deg kjøre kode skrevet i språk som C++, Rust eller Go med nesten-native hastighet inne i nettleseren. Arbeidsflyten for videobehandling blir:

1. I JavaScript: Bruk videoFrame.copyTo() for å få de rå pikseldataene inn i et ArrayBuffer.
2. Send til WASM: Send en referanse til denne bufferen til din kompilerte WASM-modul. Dette er en veldig rask operasjon da den ikke innebærer kopiering av data.
3. I WASM (C++/Rust): Utfør dine høyt optimaliserte bildebehandlingsalgoritmer direkte på minnebufferen. Dette er mange ganger raskere enn en JavaScript-løkke.
4. Returner til JavaScript: Når WASM er ferdig, returnerer kontrollen til JavaScript. Du kan deretter bruke den modifiserte bufferen til å lage en ny VideoFrame.

For enhver seriøs sanntidsapplikasjon for videomanipulering – som virtuelle bakgrunner, objektdeteksjon eller komplekse filtre – er bruk av WebAssembly ikke bare et alternativ; det er en nødvendighet.

Håndtering av forskjellige pikselformater (f.eks. I420, NV12)

Selv om RGBA er enkelt, vil du oftest motta rammer i planare YUV-formater fra en VideoDecoder. La oss se på hvordan man håndterer et fullstendig planart format som I420.

En VideoFrame i I420-format vil ha tre layout-beskrivere i sin layout-matrise:

• layout[0]: Y-planet (luma). Dimensjoner er codedWidth x codedHeight.
• layout[1]: U-planet (krominans). Dimensjoner er codedWidth/2 x codedHeight/2.
• layout[2]: V-planet (krominans). Dimensjoner er codedWidth/2 x codedHeight/2.

Slik ville du kopiert alle tre planene inn i en enkelt buffer:

async function extractI420Planes(videoFrame) {
  const totalSize = videoFrame.allocationSize({ format: 'I420' });
  const allPlanesData = new Uint8Array(totalSize);

  const layouts = await videoFrame.copyTo(allPlanesData);

  // layouts er en array med 3 PlaneLayout-objekter
  console.log('Y Plane Layout:', layouts[0]); // { offset: 0, stride: ... }
  console.log('U Plane Layout:', layouts[1]); // { offset: ..., stride: ... }
  console.log('V Plane Layout:', layouts[2]); // { offset: ..., stride: ... }

  // Du kan nå få tilgang til hvert plan i `allPlanesData`-bufferen
  // ved å bruke dets spesifikke offset og stride.

  const yPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[0].offset,
    layouts[0].stride * videoFrame.codedHeight
  );

  // Merk at krominans-dimensjonene er halvert!
  const uPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[1].offset,
    layouts[1].stride * (videoFrame.codedHeight / 2)
  );

  const vPlaneView = new Uint8Array(
    allPlanesData.buffer,
    layouts[2].offset,
    layouts[2].stride * (videoFrame.codedHeight / 2)
  );

  console.log('Accessed Y plane size:', yPlaneView.byteLength);
  console.log('Accessed U plane size:', uPlaneView.byteLength);

  videoFrame.close();
}

Et annet vanlig format er NV12, som er semi-planart. Det har to plan: ett for Y, og et andre plan der U- og V-verdier er sammenflettet (f.eks. [U1, V1, U2, V2, ...]). WebCodecs API-et håndterer dette transparent; en VideoFrame i NV12-format vil ganske enkelt ha to layouts i sin layout-matrise.

Utfordringer og beste praksis

Å jobbe på dette lave nivået er kraftig, men det medfører ansvar.

Minnehåndtering er avgjørende

En VideoFrame holder på en betydelig mengde minne, som ofte administreres utenfor JavaScripts søppeloppsamlers heap. Hvis du ikke eksplisitt frigjør dette minnet, vil du forårsake en minnelekkasje som kan krasje nettleserfanen.

Kall alltid, alltid videoFrame.close() når du er ferdig med en ramme.

Asynkron natur

All datatilgang er asynkron. Applikasjonens arkitektur må håndtere flyten av Promises og async/await riktig for å unngå race conditions og sikre en jevn behandlingspipeline.

Nettleserkompatibilitet

WebCodecs er et moderne API. Selv om det støttes i alle store nettlesere, bør du alltid sjekke for tilgjengeligheten og være klar over eventuelle leverandørspesifikke implementeringsdetaljer eller begrensninger. Bruk funksjonsdeteksjon før du prøver å bruke API-et.

Konklusjon: En ny grense for video på nettet

Muligheten til å få direkte tilgang til og manipulere rå plandata i en VideoFrame via WebCodecs API-et er et paradigmeskifte for nettbaserte medieapplikasjoner. Det fjerner den svarte boksen til <video>-elementet og gir utviklere den granulære kontrollen som tidligere var forbeholdt native applikasjoner.

Ved å forstå det grunnleggende om videominne-layout – plan, stride og fargeformater – og ved å utnytte kraften i WebAssembly for ytelseskritiske operasjoner, kan du nå bygge utrolig sofistikerte videobehandlingsverktøy direkte i nettleseren. Fra sanntids fargegradering og egendefinerte visuelle effekter til maskinlæring på klientsiden og videoanalyse, er mulighetene enorme. Tidsalderen for høytytende, lavnivå video på nettet har virkelig begynt.